Get the top matching Vacancies for an Employee
curl --request POST \
  --url https://{tenant_name}.{region}.techwolf.ai/employees/{external_id}/matching_vacancies \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filters": [
    {
      "filter": "max_geo_distance",
      "max_geo_distance": 50
    },
    {
      "filter": "multi_max_geo_distances",
      "multi_max_geo_distances": [
        {
          "max_geo_distance": 20,
          "location": {
            "lat": 51.34,
            "lng": 3.15
          }
        },
        {
          "max_geo_distance": 20,
          "location": {
            "country": "BE",
            "postal_code": 9000
          }
        }
      ]
    },
    {
      "filter": "language",
      "max_overqualification": 2,
      "max_underqualification": 1
    },
    {
      "filter": "last_updated",
      "value": "2022-01-01",
      "operator": "lt"
    },
    {
      "filter": "custom_property_equal",
      "from_entity_property": "desired_wage",
      "to_entity_property": "wage"
    },
    {
      "filter": "custom_property",
      "property_name": "direct_manager",
      "property_value": "John Doe"
    },
    {
      "filter": "custom_property_is_in",
      "from_entity_property": "required_drivers_license",
      "to_entity_property": "drivers_licenses"
    },
    {
      "filter": "custom_property_is_in_list",
      "property_name": "drivers_license",
      "possible_values": [
        "C",
        "CE"
      ]
    },
    {
      "filter": "custom_property_contains",
      "from_entity_property": "shift_regime_codes",
      "to_entity_property": "desired_regime"
    },
    {
      "filter": "custom_property_list_overlap",
      "from_entity_property": "desired_industries",
      "to_entity_property": "industries"
    },
    {
      "filter": "custom_property_contains_element",
      "property_name": "industries",
      "property_value": "electronics"
    },
    {
      "filter": "external_id_is_in_list",
      "external_ids": [
        "c350500-eb84-42dc-a79f-5e7b1fe897b7",
        "b450500-eb84-42dc-a79f-5e7b1fe897c8"
      ]
    }
  ],
  "weights": [
    {
      "weight": "skills_match",
      "value": 1
    },
    {
      "weight": "desired_functions",
      "value": 0.03
    },
    {
      "weight": "geo_distance",
      "value": 0.1,
      "full_score_distance": 5,
      "zero_score_distance": 50
    },
    {
      "weight": "language",
      "value": 0.1,
      "max_overqualification": 2,
      "max_underqualification": 3
    },
    {
      "weight": "custom_property",
      "value": 0.04,
      "property_name": "yearly_salary",
      "operator": "gte",
      "property_value": 45000
    },
    {
      "weight": "custom_property_is_in",
      "value": 0.06,
      "from_entity_property": "desired_work_regime",
      "to_entity_property": "offered_work_regimes"
    },
    {
      "weight": "custom_property_is_in_list",
      "value": 0.05,
      "property_name": "region",
      "possible_values": [
        "Flanders",
        "Wallonia"
      ]
    },
    {
      "weight": "custom_property_contains",
      "value": 0.07,
      "from_entity_property": "sectors",
      "to_entity_property": "desired_sector"
    },
    {
      "weight": "custom_property_contains_element",
      "value": 0.04,
      "property_name": "industries",
      "property_value": [
        "Electronics",
        "Aviation"
      ]
    },
    {
      "weight": "custom_property_list_overlap",
      "value": 0.04,
      "from_entity_property": "desired_industries",
      "to_entity_property": "industries"
    }
  ],
  "used_event_types": [
    "working_history",
    "education_history"
  ]
}'
{
  "results": [
    {
      "employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
      "vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
      "score": 0.87657
    }
  ]
}

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
external_id
string<uuid>
required

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Required string length: 1 - 100
Example:

"a3903505-eb84-42dc-a79f-5e7b1fe897b7"

Query Parameters

​
score_min_threshold
number
default:0.5

The minimum score of the results. Due to approximations for fast result-delivery, there might be records with a score slightly lower than the minimum.

Required range: 0 <= x <= 1
Example:

0.7

​
limit
integer
default:10

The maximal number of results returned.

Required range: 1 <= x <= 100
Example:

10

​
offset
integer
default:0

The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit.

Required range: x >= 0
​
response_format
enum<string>
default:simple

If set to explained, the response will include an explanation of the match.

Available options:
simple,
explained
Example:

"explained"

​
include
enum<string>[]

Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include entity is used, the response will include the titles and descriptions of the matched Vacancies.

Example:
["custom_properties", "entity", "location"]

Body

application/json

List of filters to be applied on the entities before matching List of weights to be applied during matching

​
filters
(max_geo_distance · object | multi_max_geo_distances · object | language · object | last_updated · object | custom_property_equal · object | custom_property · object | custom_property_is_in · object | custom_property_is_in_list · object | custom_property_contains · object | custom_property_contains_element · object | custom_property_list_overlap · object | external_id_is_in_list · object | exclude_match_feedback · object)[]
required
Example:
[
  {
    "filter": "max_geo_distance",
    "max_geo_distance": 50
  },
  {
    "filter": "multi_max_geo_distances",
    "multi_max_geo_distances": [
      {
        "max_geo_distance": 20,
        "location": { "lat": 51.34, "lng": 3.15 }
      },
      {
        "max_geo_distance": 20,
        "location": { "country": "BE", "postal_code": 9000 }
      }
    ]
  },
  {
    "filter": "language",
    "max_overqualification": 2,
    "max_underqualification": 1
  },
  {
    "filter": "last_updated",
    "value": "2022-01-01",
    "operator": "lt"
  },
  {
    "filter": "custom_property_equal",
    "from_entity_property": "desired_wage",
    "to_entity_property": "wage"
  },
  {
    "filter": "custom_property",
    "property_name": "direct_manager",
    "property_value": "John Doe"
  },
  {
    "filter": "custom_property_is_in",
    "from_entity_property": "required_drivers_license",
    "to_entity_property": "drivers_licenses"
  },
  {
    "filter": "custom_property_is_in_list",
    "property_name": "drivers_license",
    "possible_values": ["C", "CE"]
  },
  {
    "filter": "custom_property_contains",
    "from_entity_property": "shift_regime_codes",
    "to_entity_property": "desired_regime"
  },
  {
    "filter": "custom_property_list_overlap",
    "from_entity_property": "desired_industries",
    "to_entity_property": "industries"
  },
  {
    "filter": "custom_property_contains_element",
    "property_name": "industries",
    "property_value": "electronics"
  },
  {
    "filter": "external_id_is_in_list",
    "external_ids": [
      "c350500-eb84-42dc-a79f-5e7b1fe897b7",
      "b450500-eb84-42dc-a79f-5e7b1fe897c8"
    ]
  }
]
​
weights
(skills_match · object | desired_functions · object | geo_distance · object | language · object | custom_property · object | custom_property_is_in · object | custom_property_is_in_list · object | custom_property_contains · object | custom_property_contains_element · object | custom_property_list_overlap · object)[]
required
Example:
[
  { "weight": "skills_match", "value": 1 },
  {
    "weight": "desired_functions",
    "value": 0.03
  },
  {
    "weight": "geo_distance",
    "value": 0.1,
    "full_score_distance": 5,
    "zero_score_distance": 50
  },
  {
    "weight": "language",
    "value": 0.1,
    "max_overqualification": 2,
    "max_underqualification": 3
  },
  {
    "weight": "custom_property",
    "value": 0.04,
    "property_name": "yearly_salary",
    "operator": "gte",
    "property_value": 45000
  },
  {
    "weight": "custom_property_is_in",
    "value": 0.06,
    "from_entity_property": "desired_work_regime",
    "to_entity_property": "offered_work_regimes"
  },
  {
    "weight": "custom_property_is_in_list",
    "value": 0.05,
    "property_name": "region",
    "possible_values": ["Flanders", "Wallonia"]
  },
  {
    "weight": "custom_property_contains",
    "value": 0.07,
    "from_entity_property": "sectors",
    "to_entity_property": "desired_sector"
  },
  {
    "weight": "custom_property_contains_element",
    "value": 0.04,
    "property_name": "industries",
    "property_value": ["Electronics", "Aviation"]
  },
  {
    "weight": "custom_property_list_overlap",
    "value": 0.04,
    "from_entity_property": "desired_industries",
    "to_entity_property": "industries"
  }
]
​
used_event_types
enum<string>[]

Type of the Skill Event. If not empty, only Skill Events of the types listed here will be taken into account to perform the matching. Learn more about the Skill Event Types at How it works.

Example:
["working_history", "education_history"]

Response

OK

​
results
Simple · object[]
required

List of match results.